<?php
/**
 * Created by PhpStorm.
 * User: hedx
 * Date: 2016/3/1
 * Time: 16:16
 */

namespace common\mq;

/**
 * 消息服务接口，所有具体的消息服务实例必须继承此接口
 *
 * Interface MessageServiceInterface
 * @package common\mq
 */
interface MessageServiceInterface
{
    /**
     * 获取消息服务客户端
     * @return mixed
     */
    public function getClient();

    /**
     * 创建一个队列，支持一对一消息的发送和接收
     *
     * @param string $queueName 队列名称
     * @param object $queueAttributes 队列属性
     * @return boolean
     */
    public function createQueue($queueName, $queueAttributes = NULL);

    /**
     * 根据队列名称删除一个队列
     *
     * @param string $queueName 队列名称
     */
    public function deleteQueue($queueName);

    /**
     * 向指定的队列发送一条消息，如果不想消息被马上消费，可以指定延时时间 delaySeconds,
     * 消息将在指定的时间后被消费，否则消息可随时被消费。如果消息发送成功则返回一个唯一
     * 的messageId用来标识此消息。
     *
     * @param string $queueName 队列名称
     * @param string $messageBody 消息主体
     * @param int $priority 消息优先级
     * @param int $delaySeconds 延时时间(默认无延时)
     * @return string messageId
     */
    public function sendMessage($queueName, $messageBody, $priority = NULL, $delaySeconds = NULL);

    /**
     * 读取某个队列的一个消息，读取成功则会调用callback回调函数消费消息，消息消费后将被删除
     *
     * @param object $queue 队列
     * @param array $callback 回调函数
     * @param array $parameters 兼容其他mq实现时的参数对象
     * @return mixed
     */
    public function receiveMessage($queue, $callback, $parameters = []);

    /**
     * 监听某个队列，如果队列中有可消费的消息则调用callback回调函数消费消息，消费完某个消息后必须确认该消息已被消费
     *
     * @param string $queueName 队列名称
     * @param array $callback 回调函数
     * @param array $parameters 兼容其他mq实现时的参数对象
     * @return mixed
     */
    public function listen($queueName, $callback, $parameters = []);

    /**
     * 监听某个队列，如果队列中有可消费的消息则调用callback回调函数消费消息，消费完某个消息后必须确认该消息已被消费
     * 此方法没有任务时不会退出
     *
     * @param string $queueName 队列名称
     * @param array $callback 回调函数
     * @param array $parameters 兼容其他mq实现时的参数对象
     * @return mixed
     */
    public function listenNoBreak($queueName, $callback, $parameters = []);

    /**
     * 创建一个主题，主题模型提供pub/sub模型，支持一对多消息的订阅和通知
     *
     * @param string $topicName 主题名称
     * @param object $topicAttributes 主题属性
     */
    public function createTopic($topicName, $topicAttributes = NULL);

    /**
     * 删除一个主题，一旦删除成功，主题内所有消息也一并删除，不可恢复
     *
     * @param $topicName
     * @return mixed
     */
    public function deleteTopic($topicName);

    /**
     * 向指定的topic发布一个订阅消息，此消息会被所有订阅了此topic的订阅者接收
     *
     * @param $topicName
     * @param $messageBody
     * @return mixed
     */
    public function publishMessage($topicName, $messageBody);

    /**
     * 获取所有的队列数组
     *
     * @return mixed
     */
    public function getAllQueueList();
}